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Summary 


• OS/2 & USB stack 

• Development environment 

• USB stack architecture 

• Interrupt processing 

• Device reservation 

• USB filter driver design 

• New features in usbmsd driver 

• Relations between usbmsd and dasd (os2&dani) 

• Known problems & restrictions 
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OS/2 & USB Stack 


• Started development in 1997 

• Limited driver support for USB 1.0/1.1 

• Added USB 2.0 support in 2002 

• Support of several class drivers: 

- HID devices (mice/keyboard) 

- Audio 

- modem/serial convertors 

- Ethernet driver 

- Mass Storage devices 

- Printers 
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Development Environment 


• IBM DDK build tree 

• Tools 

- MS C 6.0 

- Masm 

• Built-in debug/service tools 

- Serial port printout routines (impacts timing), may 
control output message level 

- parameter/message processing routines 

- C library routine replacements 

- USB data structure processing routines 

• Driver template 
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Template files 
- TM const.c 

constant definitons (names) 

- TM_data.c 

data structures, initializations 

- TMJdc.c 

IDC processor related routines 

- TMJnit.c 

initialization time routines 

- TMJrq.c 

IRQ processing routines 

- TM_segs.asm 

driver's header, segments 

- TM_strat.c 

strategy router 

- TM_.h 

master include file 

- TM_extrn.h 

data structure external definitions 

- TM_proto.h 

function prototypes 

- TM_types 

driver's type defenition 
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- Makefile 

• Template can be easily build by commands 
drive:\ddk\tools\nmake/a DEBUG=1 
drive:\ddk\tools\nmake /a 


Copyright Exigen 


n 

exigen 


USB Stack Architecture 
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USB Stack Architecture - Interfaces 
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- External interfaces 

• Mass storage device adapter driver IORB interface 

• Multimedia interface 

• NDIS 2.04 interface 

• Serial/parallel interfaces 

• mice/keyboard USB/regular device I DC interface 

- Internal (interstack) interface 

• I DC based 

• Similar to IOCTL interface 

• asynchronuous/synchronuous requests 
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USB Stack Architecture - Interfaces 


Function 

Type 

REGISTER 

sync 

SETCONF 

async 

SETINTF 

async 

PRCIRQ 

sync 

ACCIO 

async 

CANCEL 

sync 

CLRSTALL 

async 

CMPL_INI 

sync 

APM 

sync 

RES ET_PO RT 

sync 

IDLE 

sync 

CANCEL_STATE 

sync 
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USB Stack Architecture - Interfaces 


• CMPLJNI 

• sent to USBD to start host initialization when 
adapter driver has received notification from 
kernel that system is ready to switch from BIOS 
support to native drivers 

• IDLE 

• Sent once after initial device enumeration has 
been completed 
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USB Stack Architecture - Interfaces 


• RESETPORT 

Last resort to make port working, device address 
may change as enumeration will be executed again 

void ResetPort(DeviceList *const pDevice) 

{ 

USBCancel cancelRequest; // USB Cancel Request Block 
RP_GENIOCTL rpJJSBReq; //USBD Request Packet 

#ifdef DEBUG 
if (IpDevice) 

dsPrint(DBG_CRITICAL, "MSD: reset port !pDevice\r\n"); 

#endif 

//Check if device is connected 
if (!pDevice->pDevicelnfo) { 
pDevice->errorCode = IOERR_UNIT_NOT_READY; 
return; 

} 

cancelRequest.controllerld = pDevice->pDevicelnfo->ctrllD; 
cancelRequest.deviceAddress = pDevice->pDevicelnfo->deviceAddress; 
cancelRequest.endPointld = 0; 

#ifdef DEBUG 

dsPrint2(DBG_CRITICAL, "MSD: reset port %x %x\r\n", 

cancelRequest.controllerld, cancelRequest.deviceAddress); 

#endif 

setmem((PSZ)&rp_USBReq, 0, sizeof(rpJJSBReq)); 
rp_USBReq.rph.Cmd = CMDGenlOCTL; 
rp_USBReq.Category = USB_IDC_CATEGORY_USBD; 
rp_USBReq. Function = USB_IDC_FUNCTION_RESET_PORT; 
rp_USBReq.ParmPacket = (PVOID)&cancelRequest; 

USBCalllDC(gpUSBDIDC, gdsUSBIDC, (PRP_GENIOCTL)&rp_USBReq); 
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USB Stack Architecture - Interfaces 


• CANCELSTATE 

In addition to regular cancel request returns endpoint /request 
state. 

void CancelRequestWithState(USHORT prtlndex, USHORT endPoint) { 

USBCancel rb; // USB Cancel Request Block 
RP_GENIOCTL rp; // lOCtl Request Packet to USBD 
if (gPRT[prtlndex].pDevicelnfo) { 
rb.controllerld = gPRT[prtlndex].pDevicelnfo->ctrllD; 
rb.deviceAddress = gPRT[prtlndex].pDevicelnfo->deviceAddress; 
rb.endPointld = (UCHAR)endPoint; 
setmem((PSZ)&rp, 0, sizeof(rp)); 
rp.rph.Cmd = CMDGenlOCTL; 
rp.Category = USBJDC_CATEGORY_USBD; 
rp. Function = USB_IDC_FUNCTION_CANCEL_STATE; 
rp.ParmPacket = (PVOID)&rb; 

USBCalllDC(gpUSBDIDC, gdsUSBDIDC, (PRP_GENIOCTL)&rp); 
if (rp.rph.Status == USB_IDC_RC_WRONGFUNC) 

CancelRequests(prtlndex, endPoint); 

} 

} 
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USB Stack Architecture - Interfaces 


do { 

if (!(gPRT[prtlndex].wFlags & STOP_TRANSMIT)) WriteData (prtlndex); 
do { 

awakeC = DevHelp_ProcBlock((ULONG)(PUCHAR)gPRT[prtlndex].pRPWrite[CURRENT], 

(pRP->Unit)? // COM# : $USBPRT in milliseconds 
(ULONG)((gDCB[pRP->Unit-1 ].dcb.usWriteTimeout + 1 )*10) : 
gPRT[prtlndex].dwTO[WRITE_IDLE_TO], WAITJSJNTERRUPTABLE); 

} while (awakeC != WAIT_TIMED_OUT && gPRT[prtlndex].pRPWrite[CURRENT]->rph.Status == 0); 
if (awakeC == WAIT_TIMED_OUT) { 

Cancel Request YVithState(prtInclex, gPRT[prtIndex].writeEndpoint); 

DevHelp_ProcBlock((ULONG)(PUCHAR)gPRT[prtlndex].pRPWrite[CURRENT], 1000, WAITJSJNTERRUPTABLE); 
if ((pRP->Unit == 0 && gPRT[prtlndex].blnfinRetry == TRUE) || 

(pRP->Unit > 0 && gDCB[pRP->Unit-1 J.dcb.fbTimeout & F3_WJNF_TO)) 

{// to try to write the data to the USB printer 
continue; 

} else { 

gPRT[prtlndex].pRPWrite[CURRENT]->rph.Status |= STERR | ERRORJ24_WRITE_FAULT; break; 

} 

} else if (gPRT[prtlndex].wFlags & (FLUSH_OUTJNPROGRESS | WRITE_DATA_ERROR)) { 
gPRT[prtlndex].pRPWrite[CURRENT]->rph.Status &= -STBUI; break; 

} else gPRT[prtlndex].pRPWrite[CURRENT]->rph.Status = 0; 

} while (gPRT[prtlndex].wWCount < gPRT[prtlndex].wWReqCount); 
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USB Stack Architecture - Interfaces 


• APM 

Power management notification 

switch (pRP_GENIOCTL->Category) 

{ 

case USB_IDC_CATEGORY_CLASS: 
switch ( pRP_GENIOCTL->Function ) { 
case USB_IDC_FUNCTION_APM: 

APMService (pRP_GENIOCTL); 
break; //LR0619end 

} 

break; 


static void APMService (PRP_GENIOCTL pRP) { 

ULONG apmState = ((USBAPMNotification FAR *)pRP->ParmPacket)->apmState; 
if (apmState == USB_APM_SUSPEND) { 

} else if (apmState == USB_APM_RESUME) { 

} 

} 
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USB Stack Architecture - Tricks 


void CancelRequests (USHORT prtlndex, USHORT endPoint) { 
USBCancel rb; // USB Cancel Request Block 
RP_GENIOCTL rp; // lOCtl Request Packet to USBD 
if (gPRT[prtIndex].pDeviceInfo) { 
rb.controllerld = gPRT[prtlndex].pDevicelnfo->ctrllD; 
rb.deviceAddress = gPRT[prtlndex].pDevicelnfo->deviceAddress; 
rb.endPointld = (UCHAR)endPoint; 
setmem((PSZ)&rp, 0, sizeof(rp)); 
rp.rph.Cmd = CMDGenlOCTL; 
rp.Category = USB_IDC_CATEGORY_USBD; 
rp.Function = USB_IDC_FUNCTION_CANCEL; 
rp.ParmPacket = (PVOID)&rb; 

USBCalllDC (gpUSBDIDC, gdsUSBDIDC, (PRP_GENIOCTL)&rp); 

} 

} 
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USB Stack Architecture - Tricks 


#define MAX_BULK_HS_BUFFSIZE 65535 
#define MAX BULK BUFFSIZE 16384 

if (pCurrDevice->pDeviceInfo->SpeedDevice == USB_HIGH_DEV_SPEED) { 

// for USB20 driver can send/receive 3*20kb bytes simultaneously 

if (currBuffLen > MAX_BULK_HS_BUFFSIZE) ‘length = 61440; // it 3 transfer descriptors 

else { 

if (scatGatlndex != pCurrDevice->cSGList -1) { 

// adjust data length to be equal maxPacketSize*n, n = 1,2,.. 

// otherwise USB device will stall request 

‘length = (USHORT)(currBuffLen - (currBuffLen % HS_MAX_PACKET_BULK_SIZE)); 
} else // driver sends all data if it is a last item in a gather list 
‘length = (USHORT)currBuffLen; 

} 

} else { // for USB11 driver can send/receive 16kb bytes simultaneously 
if (currBuffLen >= (ULONG)gBuffSize) ‘length = gBuffSize; 
else { 

if (scatGatlndex != pCurrDevice->cSGList -1) { 

// adjust data length to be equal maxPacketSize*n, n = 1,2,.. 

// otherwise USB device will stall request 

‘length = (USHORT)(currBuffLen - (currBuffLen % FS_MAX_PACKET_BULK_SIZE)); 
} else // driver sends all data if it is a last item in a gather list 
‘length = (USHORT)currBuffLen; 

} 

} 


Copyright Exigen 


16 


* 

exigen 


USB Stack Architecture - Tricks 


• You shoud merge buffers from scatter gather list into one 
buffer and send it to USBD. 
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Interrupt Processing 

• Limited processing at IRQ time in host drivers 

• Finalizing during task time, calls initiating driver directly 

• Original request structure may not match 1-1 to one 
returned during IRQ (hostID/address/endpoint/requestdata 
fields are always restored) 

• Transfer status are reflected in request's status field and 
buffer length fields 

• New requests are/may be initiated during IRQ notification 
calls 

• Class drivers (also other ones) should not sent any 
requests to USBD driver during interrupt time (like from 
timer callback routines) 
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Device Reservation 


• Based on configuration selection 

- Must be set as soon as possible during device attach 
notification process 

- Configuration must be set via SETCONF call to USBD 

• device/interface sharing only between friendly drivers 
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USB Filter Driver 


• Uses the same interfaces as regular driver 

• Filter nature only when accepting device for service - may 
set filter driver IDC/DS addresses as per device basis 

• May send requests to USBD driver using special command 
(CMDIOCTLW instead of CMDGenlOCTL) to bypass 
filtering 

• After registration filter is called instead of host driver for 
each request, except for REGISTER /PRCIRQ / CMPLJNI 

- May update commands/data to be sent to device 

- May replace one request with one or more other 
requests to implement support for non-standard devices 
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USB Filter Driver 


- May update IRQ processing IDC/DS address 

pRB->usbDS = GetDS(); 
pRB->usblDC = (PUSBIDCEntry)&FL_idc; 

• Post request data processing during IRQ 

• Possible timeout problems when replacing single request 
with several for devices served by drivers that support 
time-outs for requests (like MSD driver) 
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USB Filter Driver 
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USB MSD Driver 


• Initial driver supports only first Logical Unit Number 0 

• Added multiple LUN support in 2004 

• Fixed several problems with device geometry detection (for 
BOT devices and for UFI devices): 

fixed CBI-NI protocol support 

fixed format for UFI 

ignored incorrect CHS geometry 

• Added USB HDD support. The key FIXED DISKS is ignored 
now. 

• Added possibility to work with USB CDRW devices. A filter 
driver must be implemented. 

• ModeSenselO command can be avoided. (/MS10_OFF) 

• Supports non-512 bytes/sector media with Dani filter. 
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USB MSD & DASD Drivers 


The following dasd drivers exists: 

• Os2dasd for MCP and ACP 

• Os2dasd for Warp4 

• Danidasd 

At present moment the latest fixes for USB mass storage 
devices have been inserted only in os2dasd for MCP: 

• Eject command can be used for hard drives. 

• Driver supports USB HDD with large media 

• Can detect partitions created by non-OS2 OS. 

• Can work with media formatted by another OS. 

• Supports non-OS2 oem names for PRM. 
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There are the following restrictions in danidasd and os2dasd 
for Warp4: 

• New key CHS can be used. MSD calculates CHS geometry 
from device geometry. This key helps to support USB drives 
with capacity more than 40GB. 

• Eject command must be rewritten. 
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Problems 


Host problems: 

• Does not support physically discontinuous buffers. 

• Does not support zero length transfers. It may be a critical 
point for some protocols. 

USBD problems: 

• Interrupt processing is incorrect if short packets are in use 
(more than one transfer descriptor). 

Class drivers' problems: 
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